---
title: Apollo MCP Server User Guide
---

<ExperimentalFeature>

This feature is [experimental](/graphos/resources/feature-launch-stages#experimental). Your questions and feedback are highly valued—don't hesitate to get in touch with your Apollo contact or post in the [Apollo Community MCP Server Category](https://community.apollographql.com/c/mcp-server/41).

</ExperimentalFeature>

A typical workflow for developing with Apollo MCP Server:
1. Download (or build) an MCP Server binary.
1. Set up the graph that the MCP Server sits in front of.
1. Define the GraphQL operations to expose as MCP tools.
1. Configure and run your MCP Server.
1. Connect an MCP client and run the tools.

## How to get Apollo MCP Server

### Linux / MacOS installer

To install or upgrade to the **latest release** of Apollo MCP Server:

```sh showLineNumbers=false
curl -sSL https://mcp.apollo.dev/download/nix/latest | sh
```

To install or upgrade to a **specific version** of Apollo MCP Server (recommended for CI environments to ensure predictable behavior):

```bash
# Note the `v` prefixing the version number
curl -sSL https://mcp.apollo.dev/download/nix/v0.2.1 | sh
```

If your machine doesn't have the `curl` command, you can get the latest version from the [`curl` downloads page](https://curl.se/download.html).

<Note>

These installation methods currently don't support Intel-based Macs. Support is planned for a future release.

</Note>

### Windows PowerShell installer

To install or upgrade to the **latest release** of Apollo MCP Server:

```bash
iwr 'https://mcp.apollo.dev/download/win/latest' | iex
```

To install or upgrade to a **specific version** of Apollo MCP Server (recommended for CI environments to ensure predictable behavior):

```bash
# Note the `v` prefixing the version number
iwr 'https://mcp.apollo.dev/download/win/v0.2.1' | iex
```

{/* ### Download container image

TODO */}

## Set up graph

An Apollo MCP Server must know the schema of GraphQL API it supports. You can use either [the `--schema` or `--uplink` option](/apollo-mcp-server/command-reference#options) to provide the schema. If using `--schema` option, it can be either an API or supergraph schema.

The schema is required for three main purposes:

1. **Tool Descriptions**: The schema provides type information used to generate tool descriptions. You can override these descriptions by adding comments to your operation files.
1. **Input Validation**: The schema is used to translate GraphQL input types into JSON Schema, ensuring that AI models provide correctly formatted inputs.
1. **Introspection Support**: If you enable the `--introspection` option, the schema is used to provide information about available types and operations to AI models.

## Define GraphQL operations for tools

You can manually define the GraphQL operations that are exposed by Apollo MCP Server as MCP tools. You can define these operations using:

- Operation files
- Persisted query manifests
- GraphOS-managed persisted queries

Alternatively, you can let an AI model read your graph schema via GraphQL introspection and have it determine the available operations. 

### From operation files

An operation file is a `.graphql` file containing a single GraphQL operation. 

<CodeColumns cols={2}>

```graphql title="Example operation GetForecast"
query GetForecast($coordinate: InputCoordinate!) {
  forecast(coordinate: $coordinate) {
    detailed
  }
}
```

```graphql title="Example operation GetWeatherData"
query GetAllWeatherData($coordinate: InputCoordinate!, $state: String!) {
  forecast(coordinate: $coordinate) {
    detailed
  }
  alerts(state: $state) {
    severity
    description
    instruction
  }
}
```

</CodeColumns>

The `--operations` option of the MCP Server provides it with a list of operation files. For each operation file you provide, the MCP Server creates an MCP tool that calls the corresponding GraphQL operation.

The `--operations` option can also be used to specify a directory. All files with a `.graphql` extension in the directory will be loaded as operations.

Files and directories specified with `--operations` will be hot reloaded. When specifying a file, the MCP tool will be updated when the file contents are modified. When specifying a directory, operations exposed as MCP tools will be updated when files are added, modified, or removed from the directory.

### From persisted query manifests

Apollo MCP Server supports reading GraphQL operations from Apollo-formatted [persisted query manifest](/graphos/platform/security/persisted-queries#manifest-format) files.

You can set the persisted query manifest file for the MCP Server by using the `--manifest` option. The MCP Server supports hot reloading of persisted query manifests, so changes to manifests are applied without restarting.

An example manifest is available in the [GitHub repo](https://github.com/apollographql/apollo-mcp-server/tree/main/graphql/weather/persisted_queries).

<ExpansionPanel title="Example command using --manifest">

From the root of a local MCP Server repo, run the `apollo-mcp-server` binary with the example persisted query manifest, `graphql/weather/persisted_queries/apollo.json`:

```sh showLineNumbers=false
apollo-mcp-server \
  --directory <absolute path to this local repo> \
  -s graphql/weather/api.graphql \
  --header "apollographql-client-name:my-web-app" \
  --manifest graphql/weather/persisted_queries/apollo.json
```

</ExpansionPanel>

### From GraphOS-managed persisted queries

For graphs managed by GraphOS, Apollo MCP Server can get operations by reading persisted queries from GraphOS. The MCP Server uses Apollo Uplink to access the persisted queries.

To use GraphOS persisted queries, you must:
- Set `APOLLO_GRAPH_REF` and `APOLLO_KEY` environment variables for a GraphOS graph
- Run Apollo MCP Server with the `--uplink` option

<Tip>

Use a [contract variant](/graphos/platform/schema-management/delivery/contracts/overview) with a persisted query list associated with that variant, so you can control what AI can consume from your graph. [Learn more](/apollo-mcp-server/best-practices#use-contract-variants-to-control-ai-access-to-graphs).

</Tip>


```sh title="Example command using GraphOS-managed persisted queries"
apollo-mcp-server \
  --directory <absolute path to this git repo> \
  -s graphql/weather/api.graphql \
  --header "apollographql-client-name:my-web-app" \
  --uplink
```

The MCP Server supports hot reloading of GraphOS-managed persisted queries, so it can automatically pick up changes from GraphOS without restarting.

If you register a persisted query with a specific client name instead of `null`, you must configure the MCP Server to send the necessary header indicating the client name to the router. 

Use the `--header` option when running the MCP Server to pass the header to the router. The default name of the header expected by the router is `apollographql-client-name`. To use a different header name, configure `telemetry.apollo.client_name_header` in router YAML configuration. 


### From schema introspection

For use cases where not all operations can be pre-defined, Apollo MCP Server supports tool creation based on introspection of the graph schema. This allows AI agents to explore a graph and execute operations dynamically.  

To enable these schema-aware tools, run the MCP Server with the `--introspection` option, which exposes two new tools:

* `introspect` - returns information about schema types
* `execute` - executes an operation on the GraphQL endpoint

The MCP client can use these tools to provide schema information to the model and its context window, and allow the model to execute GraphQL operations based on that schema.

<Tip>

Use a [contract variant](/graphos/platform/schema-management/delivery/contracts/overview) so you can control the parts of your graph that AI can introspect. [Learn more](/apollo-mcp-server/best-practices#use-contract-variants-to-control-ai-access-to-graphs)

</Tip>
{/* 
### Documenting tools

TODO

## Deploying a container

Apollo MCP Server is available as a standalone docker container. Container images are downloadable from TBD.

By default, the container expects all schema and operation files to be present in the `/data` folder within the container.

An example `docker run` command that runs the MCP Server for the weather example:

```sh
docker run \
  -it --rm \
  --name apollo-mcp-server \
  -p 5000:5000 \
  -v $PWD/graphql/weather:/data \
  ghcr.io/apollographql/apollo-mcp-server:latest \
  --http-port 5000 \
  -s api.graphql \
  -o operations/forecast.graphql operations/alerts.graphql operations/all.graphql
``` */}

## Debugging with MCP Inspector

[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a debugging tool for MCP servers.

### Debug locally over stdio transport

You can inspect a local Apollo MCP Server by running it with MCP Inspector. 

1. Run the MCP Server with Inspector:

```sh
npx @modelcontextprotocol/inspector \
  target/debug/apollo-mcp-server \
  --directory <absolute path to this git repo> \
  -s graphql/weather/api.graphql \
  -o graphql/weather/operations/forecast.graphql graphql/weather/operations/alerts.graphql graphql/weather/operations/all.graphql
```

<ExpansionPanel title="Example output">

```sh showLineNumbers=false disableCopy=true
Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
```
</ExpansionPanel>

1. In a browser, go to the URL returned by Inspector, then click **Connect** and **List Tools**. You should see the tools for the operations you provided.

### Debug over the Streamable HTTP transport

When running the MCP Server over the Streamable HTTP transport, you can run MCP Inspector as follows.

1. Start the MCP Server in Streamable HTTP mode:

```sh
target/debug/apollo-mcp-server \
  --directory <absolute path to this git repo> \
  --http-port 5000 -s graphql/weather/api.graphql \
  -o graphql/weather/operations/forecast.graphql graphql/weather/operations/alerts.graphql graphql/weather/operations/all.graphql
```

1. Start the MCP Inspector:

```sh
npx @modelcontextprotocol/inspector
```

1. In a browser, go to the URL returned by Inspector, then fill in the details:
    - **Transport Type**: Select `Streamable HTTP`
    - **URL**: Enter `http://localhost:5000/mcp`, where the port must match the `--http-port` option

1. Click **Connect** and **List Tools**. You should see the tools for the operations you provided.